Discovery API - Test icon

Discovery API - Test

1.0.x
(0 reviews)

Example - Discovery and Ordering (end to end)

This example uses the Discovery API and Orders API together to discover title and property information, list available products, place an order, and retrieved the ordered items.

This example assumes you are already familar with the ideas discuss in the "Relationship of properties, parcels and titles" page.

The Discovery API is designed so that you can give it the identifiers you know and it will return related property, parcel, and title entities.

In this example we'll start with an SPI (a parcel identifier) and use the GET /discovery/v1/parcels operation to find related titles and properties. The end to end flow is similar if you start with a title or property identifier instead. If we started instead with a title identifier we could use the GET /discovery/v1/titles operation to find related properties (and parcels). If we started with a property identifier we could use GET /discovery/v1/properties to find related titles (and parcels).

At the end of this step we want to have a titleId or propertyPfi which we can list products for in the next step. If you already know the titleId (volume/folio) or propertyPfi of the title or property you want to see products for then this step can be skipped.

Example request

The GET /discovery/v1/parcels accepts a query parameter 'spi' (note that query parameters must be URL Encoded - most HTTP libraries will handle this automatically).

curl --request GET \
  --location 'https://test.api.servictoria.io/ddp/discovery/v1/parcels?spi=3A2%5CPS515587' \
  --header 'Authorization: Bearer ******'
Example response

The response will include a summary or the parcel as well as all the titles and properties related to the parcel.

Titles are typically uniquely identified by a volume/folio (eg '10940/843') however since a fee is charged to lookup volume/folios this API instead returns an encrypted titleId without incurring a cost.

{
    "spi": "3A2\\PS515587",
    "parcelType": "LOT",
    "parcelStatus": "ACTIVE",
    "isPartParcel": false,
    "parcelDetails": {
        "lot": "3A2",
        "planNumber": "PS515587S"
    },
    "titles": [
        {
            "titleId": "qp0gjuieZ5VzbNKtT/eZvqPryobRkEYxMA==",
            "titleStatus": "ACTIVE",
            "titleType": "FREEHOLD"
        }
    ],
    "properties": [
        {
            "propertyPfi": "208045794",
            "isMultiAssess": false,
            "propertyStatus": "ACTIVE"
        },
        {
            "propertyPfi": "220476599",
            "isMultiAssess": false,
            "propertyStatus": "ACTIVE"
        },
        {
            "propertyPfi": "208045633",
            "isMultiAssess": false,
            "propertyStatus": "ACTIVE"
        }
    ]
}

2. Use Orders API to list products for a title (or property)

In this step we'll take the titleId discovered in the previous step (qp0gjuieZ5VzbNKtT/eZvqPryobRkEYxMA==) and get a list of products for that title.

The GET /orders/v1/products operation accepts a query parameter 'titleId' which can be either a volume/folio (eg '10940/843') or encrypted title id (eg 'qp0gjuieZ5VzbNKtT/eZvqPryobRkEYxMA=='). If we wanted a list of property related products we could provide a propertyPfi (eg '208045794') query parameter instead.

At the end of this step we will have the productCode and productIds for the products we wish to order. If we already know the productCode and which productIds are required for the product(s) we want then this step can be skipped.

Example request
curl --request GET \
  --location 'https://test.api.servictoria.io/ddp/orders/v1/products?titleId=qp0gjuieZ5VzbNKtT%2FeZvqPryobRkEYxMA%3D%3D' \
  --header 'Authorization: Bearer ******'

The response will include a list of products related to this title. The availability of products will depend on the title, including whether its crown or freehold, under an owner's corporation or in a specific location, etc...

Each product in the response is uniquely identified by the combination of it's productCode and productIds.

{
    "products": [
        {
            "productCode": "RegisterSearchStatement",
            "productIds": {
                "titleId": "qp0gjuieZ5VzbNKtT/eZvqPryobRkEYxMA=="
            },
            "productName": "Register Search Statement (Copy of Title)",
            "productDescription": "PDF version of the copy of the Title, lists the current registered proprietors, any encumbrances, caveats or notices that apply to the land, but does not include a sketch of the plan.",
            "productAvailability": "AVAILABLE",
            "authorityName": "Land Registry",
            "price": 640,
            "gst": 0,
            "turnaroundTime": 5,
            "turnaroundTimeUnit": "MIN"
        },
        {
            "productCode": "CopyOfPlan",
            "productIds": {
                "documentId": "PS515587S"
            },
            "productName": "Copy of Plan",
            "productDescription": "Shows the subdivision of an original parcel of land, including legal boundaries and location of the parcel(s).",
            "productAvailability": "AVAILABLE",
            "authorityName": "Land Registry",
            "price": 640,
            "gst": 0,
            "turnaroundTime": 10,
            "turnaroundTimeUnit": "DAY"
        },
        ...
    ]
}

3. Order a Register Search Statement and Copy of Plan

To order these products we use the POST /orders/v1 operation and supply the products productCode and productIds.

Example request

In the 'customer-id' header an identifier is provided to indicate this order is for a specific child customer (this ID can be anything under 40 characters). The GET /orders/v1 operation can then be used later on to get an order history for just this child customer using the same 'customer-id' header value.

curl --request POST
  --location 'https://test.api.servictoria.io/ddp/orders/v1' \
  --header 'customer-id: example123' \
  --header 'customer-reference: Example customer reference' \
  --header 'Authorization: Bearer ******' \
  --data-raw '{
    "products": [
      {
        "productCode": "RegisterSearchStatement",
        "productIds": {
          "titleId": "qp0gjuieZ5VzbNKtT/eZvqPryobRkEYxMA=="
        }
      },
      {
        "productCode": "CopyOfPlan",
        "productIds": {
          "documentId": "PS515587S"
        }
      }
    ],
    "deliveryPreference": "EMAIL",
    "email": "john.citizen@example.com",
    "contactName": "John Citizen",
    "contactNumber": "03 5550 1234"
  }'
Example response

The response will include an orderId as well as an orderItemNumber for each product ordered. These can be used in the next steps to look up this order and obtain the fulfilled products.

{
    "orderId": "11828172",
    "totalPrice": 2074,
    "totalGst": 72,
    "fees": [
        {
            "type": "Land Index Search Charge",
            "amount": 794,
            "gst": 72
        }
    ],
    "itemsOrdered": [
        {
            "orderItemNumber": 1,
            "productCode": "RegisterSearchStatement",
            "productIds": {
                "titleId": "10940/843"
            },
            "productName": "Register Search Statement (Copy of Title)",
            "authorityName": "Land Registry",
            "price": 640,
            "gst": 0,
            "discounts": []
        },
        {
            "orderItemNumber": 2,
            "productCode": "CopyOfPlan",
            "productIds": {
                "documentId": "PS515587S"
            },
            "productName": "Copy of Plan",
            "authorityName": "Land Registry",
            "price": 640,
            "gst": 0,
            "discounts": []
        }
    ]
}

4. Retrieve order details

The GET /orders/v1/{orderId} operation can be used to retrieve details about an order including the status of ordered items.

Example request
curl --request GET \
  --location 'https://test.api.servictoria.io/ddp/orders/v1/11828172' \
  --header 'customer-id: example123' \
  --header 'Authorization: Bearer ******'
Example response
{
    "orderId": "11828172",
    "orderDate": "2024-08-12T11:20:03.980000+10:00",
    "totalPrice": 2074,
    "totalGst": 72,
    "fees": [
        {
            "type": "Land Index Search Charge",
            "amount": 794,
            "gst": 72
        }
    ],
    "deliveryPreference": "EMAIL",
    "email": "john.citizen@example.com",
    "contactName": "John Citizen",
    "customerReference": "Example customer reference",
    "products": [
        {
            "orderItemNumber": 1,
            "productCode": "RegisterSearchStatement",
            "productIds": {
                "titleId": "10940/843"
            },
            "productName": "Register Search Statement (Copy of Title)",
            "authorityName": "Land Registry",
            "productStatus": "COMPLETE",
            "price": 640,
            "gst": 0
        },
        {
            "orderItemNumber": 2,
            "productCode": "CopyOfPlan",
            "productIds": {
                "documentId": "PS515587S"
            },
            "productName": "Copy of Plan",
            "authorityName": "Land Registry",
            "productStatus": "COMPLETE",
            "price": 640,
            "gst": 0
        }
    ]
}

4. Retrieve ordered product

The GET /orders/v1/{orderId}/item/{orderItemNumber} operation can be used to retrieve a specifc ordered product.

Example request
curl --request GET \
  --location 'https://test.api.servictoria.io/ddp/orders/v1/11828172/item/1' \
  --header 'customer-id: example123' \
  --header 'Authorization: Bearer ******'
Example response (PROCESSING)

This operation can be polled every to check the status of the order. In the example below the "productStatus" is still "PROCESSING".

{
    "orderId": "11828172",
    "orderItemNumber": 1,
    "productName": "Register Search Statement (Copy of Title)",
    "productStatus": "PROCESSING",
    "customerReference": "Example customer reference"
}
Example response (COMPLETE)

Once the order has been successfully processed "productStatus" will be "COMPLETE" and the response will include the product output.

In this example the product PDF can be downloaded using the link in the resourceLocation field. The link has a 24 hour expiry but this operation can be called again to get a fresh link.

{
    "orderId": "11828172",
    "orderItemNumber": 1,
    "productName": "Register Search Statement (Copy of Title)",
    "productStatus": "COMPLETE",
    "customerReference": "Example customer reference",
    "resourceText": "Copyright State of Victoria ... RSS text ... DOCUMENT END",
    "resourceLocation": "https://test.link.servictoria.io/Certificates/00118281720012024081201200001.pdf?Expires=1723460801&Signature=Uh3bT6kakQCHVReBYI6SUFfBWuL4kuJJKv5-HYOMOgEKCUeP-VY3seos~bS4Od0Jj1KfBvE1B3bIf-1i0WvikB0KAEgEgJvyY-oCbTSid0IgZv6VK3t~smRnV2XRhfH5PxkshQrYm8EIiLo9MMdhF8uiJAycuV1JGZzvUMKLZnWbJ6IpDHo8pik3p3Sed67XYQQfRYxyuKXyrVGVr2J6pwAP~zbsdUhqqcmtKL-Jr80mlB-Q7xFST1315eaiaxRMzpyHG3pcWiRcgaj0InY2yVhjDbakrISzQe1qohrwQHnxlEc5mfVEmhpO1WmUcnpN2gMp6icZIV7lPlU-HkoA0A__&Key-Pair-Id=KK3F67ER9XK0L",
    "resourceExpiry": "2024-08-12T21:06:41.159656+11:00",
    "resourceFileType": "PDF",
    "resourceFileSize": 6234
}

Reviews